Skip to content

docs: add CLAUDE.md, architecture docs, and /sesh-mode skill#6247

Open
g-talbot wants to merge 4 commits intogtt/phase-31-executefrom
gtt/docs-claude-md
Open

docs: add CLAUDE.md, architecture docs, and /sesh-mode skill#6247
g-talbot wants to merge 4 commits intogtt/phase-31-executefrom
gtt/docs-claude-md

Conversation

@g-talbot
Copy link
Copy Markdown

@g-talbot g-talbot commented Mar 30, 2026

Summary

  • Adds CLAUDE.md with development guide, coding standards, known pitfalls, and repo layout
  • Adds docs/internals architecture documentation: ADRs (4 decisions + 10 gap analyses), TLA+ formal specs (ParquetDataModel, SortSchema, TimeWindowedCompaction), verification guides, style references, and compaction architecture
  • Splits CLAUDE.md into universal repo context (auto-loaded) + opt-in /sesh-mode skill for verification-first workflow (TLA+, DST, Stateright)

Combines pomsky PRs #468 and #474.

Stacks on gtt/phase-31-execute (PR #6246).

The split logic (from PR #474)

Stays in CLAUDE.md Moves to /sesh-mode
What CI already enforces What requires human buy-in
Factual repo structure Workflow sequencing
"Don't do X" (pitfalls) "You must do X before Y" (process)
Coding conventions Formal verification requirements
Defensive Rust patterns TLA+, Stateright, DST

Test plan

  • Verify CLAUDE.md references correct paths for this repo
  • Verify docs/internals files are present and readable
  • /sesh-mode skill contains the full verification workflow
  • No code changes — documentation only

🤖 Generated with Claude Code

@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 0ee18f5 to b077bf3 Compare March 31, 2026 20:41
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from ae409ac to 3eb3316 Compare March 31, 2026 20:41
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 70a48be to d225cc7 Compare March 31, 2026 20:55
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch 2 times, most recently from c4418dd to aa5ff45 Compare March 31, 2026 21:03
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch 2 times, most recently from 8d701de to bcdda05 Compare March 31, 2026 21:08
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch 2 times, most recently from 142ddd6 to 972bd20 Compare March 31, 2026 21:26
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from bcdda05 to 0fd7087 Compare March 31, 2026 21:26
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch 2 times, most recently from 73c90c4 to 44bd6bb Compare March 31, 2026 21:31
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 468ac45 to 1e5722d Compare March 31, 2026 21:31
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from 44bd6bb to add1902 Compare March 31, 2026 21:33
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 1e5722d to 9b6c961 Compare March 31, 2026 21:33
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from add1902 to d88f67f Compare March 31, 2026 21:40
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch 2 times, most recently from 06a6296 to 8f1cbde Compare March 31, 2026 21:50
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch 2 times, most recently from b5b840e to c8e6070 Compare April 1, 2026 10:48
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 8f1cbde to a8d60a7 Compare April 1, 2026 10:48
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from c8e6070 to cc704b5 Compare April 1, 2026 11:02
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from a8d60a7 to b2bde05 Compare April 1, 2026 11:02
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from cc704b5 to bf93060 Compare April 1, 2026 11:10
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from b2bde05 to 075e9c3 Compare April 1, 2026 11:10
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from bf93060 to cedd6ca Compare April 1, 2026 11:30
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 075e9c3 to 01e7e3b Compare April 1, 2026 11:30
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from cedd6ca to 02cf95d Compare April 1, 2026 12:25
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 7b0bb80 to d5dae8a Compare April 1, 2026 15:20
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch 2 times, most recently from 5b78b1e to c9634ed Compare April 1, 2026 15:30
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch 2 times, most recently from 9ba9f49 to 1a1b5ea Compare April 1, 2026 15:34
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from c9634ed to 1df615d Compare April 1, 2026 15:34
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch 2 times, most recently from afdec4e to 2acbcf3 Compare April 1, 2026 16:25
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from 1df615d to 0c39228 Compare April 1, 2026 16:25
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 2acbcf3 to 977badb Compare April 1, 2026 16:59
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from 0c39228 to 3b1e48d Compare April 1, 2026 16:59
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 977badb to cb8afea Compare April 1, 2026 18:18
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from 3b1e48d to 251ec57 Compare April 1, 2026 18:18
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch 2 times, most recently from 75a584b to fa3fd92 Compare April 1, 2026 18:36
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch 2 times, most recently from c4cbf0e to a96e8f5 Compare April 1, 2026 19:24
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from fa3fd92 to 5d2f8b7 Compare April 1, 2026 19:24
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from a96e8f5 to 9f71553 Compare April 1, 2026 20:18
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 5d2f8b7 to 3d19eb9 Compare April 1, 2026 20:22
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from 9f71553 to d7a7e05 Compare April 1, 2026 20:50
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 3d19eb9 to 7b198eb Compare April 1, 2026 20:50
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from d7a7e05 to 2c2eea2 Compare April 1, 2026 21:01
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 7b198eb to 151688e Compare April 1, 2026 21:01
g-talbot and others added 4 commits April 1, 2026 17:13
@g-talbot @claude
docs: add CLAUDE.md and docs/internals architecture documentation
58ecd0f 
Ports CLAUDE.md (development guide, coding standards, known pitfalls) and
the full docs/internals tree including ADRs, gap analyses, TLA+ specs,
verification guides, style references, and compaction architecture.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@hushy @claude @g-talbot
docs: split CLAUDE.md into repo context + opt-in /sesh-mode skill
1d608e3 
- Move verification-first workflow (TLA+, DST, formal specs) to /sesh-mode skill
- Keep repo knowledge in CLAUDE.md (pitfalls, reliability rules, testing, docker, commands)
- Remove Crate Map (derivable from filesystem)
- Remove Coding Style bullet summary (CODE_STYLE.md is linked)
- Fix relative links in SKILL.md for .claude/skills/sesh-mode/ path

Co-Authored-By: Claude <noreply@anthropic.com>
@g-talbot
docs: add machete, cargo doc, and fmt details to CI checklist in CLAU…
28cc570 
…DE.md
@g-talbot
review: parquet_file singular, proto doc link, fix metastore accessor
b6da436
@g-talbot g-talbot force-pushed the gtt/phase-31-execute branch from 2c2eea2 to 29cc07f Compare April 1, 2026 21:14
@g-talbot g-talbot force-pushed the gtt/docs-claude-md branch from 151688e to b6da436 Compare April 1, 2026 21:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@fulmicoton-dd fulmicoton-dd Awaiting requested review from fulmicoton-dd

@mattmkim mattmkim Awaiting requested review from mattmkim

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@g-talbot @hushy